<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>Hoodoo::Client::Headers</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" href="../../../css/reset.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/main.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/github.css" type="text/css" media="screen" />
<script src="../../../js/jquery-1.3.2.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/jquery-effect.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/main.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/highlight.pack.js" type="text/javascript" charset="utf-8"></script>

</head>

<body>
    <div class="banner">
        <h1>
            <span class="type">Class</span>
            Hoodoo::Client::Headers
                <span class="parent">&lt;
                    Object
                </span>
        </h1>
        <ul class="files">
            <li><a href="../../../files/lib/hoodoo/client/headers_rb.html">lib/hoodoo/client/headers.rb</a></li>
            <li><a href="../../../files/lib/hoodoo/services/middleware/middleware_rb.html">lib/hoodoo/services/middleware/middleware.rb</a></li>
            <li><a href="../../../files/lib/hoodoo/services/services/context_rb.html">lib/hoodoo/services/services/context.rb</a></li>
        </ul>
    </div>
    <div id="bodyContent">
        <div id="content">
    <div class="description">
      
<p><a href="../Client.html">Hoodoo::Client</a> and related software such as <a
href="../Services/Middleware.html">Hoodoo::Services::Middleware</a> need
common access to information about special processing headers defined by <a
href="../../Hoodoo.html">Hoodoo</a> and the <a
href="../../Hoodoo.html">Hoodoo</a> API. This class is just a container -
pretty much a namespaced library - holding that kind of information and
support methods.</p>

    </div>








    <!-- Method ref -->
    <div class="sectiontitle">Methods</div>
    <dl class="methods">
        <dt>D</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-define_accessors_for_header_equivalents">define_accessors_for_header_equivalents</a>
              </li>
          </ul>
        </dd>
        <dt>X</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-x_header_to_options">x_header_to_options</a>
              </li>
          </ul>
        </dd>
    </dl>







      <!-- Section constants -->
      <div class="sectiontitle">Constants</div>
      <table border='0' cellpadding='5'>
          <tr valign='top' id='UUID_PROPERTY_PROC'>
            <td class="attr-name">UUID_PROPERTY_PROC</td>
            <td>=</td>
            <td class="attr-value"><pre>-&gt; ( value ) {
value = Hoodoo::UUID.valid?( value ) &amp;&amp; value
value || nil # =&gt; &#39;value&#39; if &#39;value&#39; is truthy, &#39;nil&#39; if &#39;value&#39; falsy
}</pre></td>
          </tr>
            <tr valign='top'>
              <td>&nbsp;</td>
              <td colspan="2" class="attr-desc"><p>Used by <a href="Headers.html#HEADER_TO_PROPERTY">HEADER_TO_PROPERTY</a>;
this Proc when called with some non-nil value from an HTTP header
representing a <a href="../UUID.html">UUID</a>, evaluates to either the <a
href="../UUID.html">UUID</a> as a String or <code>nil</code> if the value
appeared to not be a <a href="../UUID.html">UUID</a>.</p></td>
            </tr>
          <tr valign='top' id='UUID_HEADER_PROC'>
            <td class="attr-name">UUID_HEADER_PROC</td>
            <td>=</td>
            <td class="attr-value"><pre>-&gt; ( value ) { value }</pre></td>
          </tr>
            <tr valign='top'>
              <td>&nbsp;</td>
              <td colspan="2" class="attr-desc"><p>Used by <a href="Headers.html#HEADER_TO_PROPERTY">HEADER_TO_PROPERTY</a>;
this Proc when called with some <a href="../UUID.html">UUID</a> evaluates
to the input value coerced to a String and no other changes.</p></td>
            </tr>
          <tr valign='top' id='KVP_PROPERTY_PROC'>
            <td class="attr-name">KVP_PROPERTY_PROC</td>
            <td>=</td>
            <td class="attr-value"><pre>-&gt; ( value ) {
Hash[ URI.decode_www_form( value ) ]
}</pre></td>
          </tr>
            <tr valign='top'>
              <td>&nbsp;</td>
              <td colspan="2" class="attr-desc"><p>Used by <a href="Headers.html#HEADER_TO_PROPERTY">HEADER_TO_PROPERTY</a>;
this Proc when called with some non-nil value from an HTTP header
containing URL-encoded simple key/value pair data returns a decoded Hash of
key/value pairs. Use URL encoding in the HTTP header value as per:</p>

<p><a
href="http://www.w3.org/TR/html5/forms.html#url-encoded-form-data">www.w3.org/TR/html5/forms.html#url-encoded-form-data</a></p>

<p>Invalid input will produce unusual results, e.g. an empty Hash or a Hash
where certain keys may have empty string values.</p></td>
            </tr>
          <tr valign='top' id='KVP_HEADER_PROC'>
            <td class="attr-name">KVP_HEADER_PROC</td>
            <td>=</td>
            <td class="attr-value"><pre>-&gt; ( value ) {
URI.encode_www_form( value )
}</pre></td>
          </tr>
            <tr valign='top'>
              <td>&nbsp;</td>
              <td colspan="2" class="attr-desc"><p>Used by <a href="Headers.html#HEADER_TO_PROPERTY">HEADER_TO_PROPERTY</a>;
this Proc when called with some non-nested Hash evaluates to a URL-encoded
form data String as per:</p>

<p><a
href="http://www.w3.org/TR/html5/forms.html#url-encoded-form-data">www.w3.org/TR/html5/forms.html#url-encoded-form-data</a></p></td>
            </tr>
          <tr valign='top' id='DATETIME_IN_PAST_ONLY_PROPERTY_PROC'>
            <td class="attr-name">DATETIME_IN_PAST_ONLY_PROPERTY_PROC</td>
            <td>=</td>
            <td class="attr-value"><pre>-&gt; ( value ) {
value = Hoodoo::Utilities.valid_iso8601_subset_datetime?( value )
value = nil if value &amp;&amp; value &gt; DateTime.now
value || nil # =&gt; &#39;value&#39; if &#39;value&#39; is truthy, &#39;nil&#39; if &#39;value&#39; falsy
}</pre></td>
          </tr>
            <tr valign='top'>
              <td>&nbsp;</td>
              <td colspan="2" class="attr-desc"><p>Used by <a href="Headers.html#HEADER_TO_PROPERTY">HEADER_TO_PROPERTY</a>;
this Proc when called with some non-nil value from an HTTP header
representing a Date/Time in a supported format, evaluates to either a
parsed DateTime instance or <code>nil</code> if the value appeared to not
be in a supported format.</p></td>
            </tr>
          <tr valign='top' id='DATETIME_WRITER_PROC'>
            <td class="attr-name">DATETIME_WRITER_PROC</td>
            <td>=</td>
            <td class="attr-value"><pre>-&gt; ( value ) { Hoodoo::Utilities.rationalise_datetime( value ) }</pre></td>
          </tr>
            <tr valign='top'>
              <td>&nbsp;</td>
              <td colspan="2" class="attr-desc"><p>Used by <a href="Headers.html#HEADER_TO_PROPERTY">HEADER_TO_PROPERTY</a>;
this Proc is called with a Time, Date, DateTime or DateTime-parseable
String and returns a DateTime. It is used for a custom write accessor for
the property associated with a header entry and works independently of the
validation mechanism for inbound String-only from-header data.</p></td>
            </tr>
          <tr valign='top' id='DATETIME_HEADER_PROC'>
            <td class="attr-name">DATETIME_HEADER_PROC</td>
            <td>=</td>
            <td class="attr-value"><pre>-&gt; ( value ) { Hoodoo::Utilities.nanosecond_iso8601( value ) }</pre></td>
          </tr>
            <tr valign='top'>
              <td>&nbsp;</td>
              <td colspan="2" class="attr-desc"><p>Used by <a href="Headers.html#HEADER_TO_PROPERTY">HEADER_TO_PROPERTY</a>;
this Proc when called with a DateTime instance evaluates to a String
representing the DateTime as an ISO 8601 subset value given to nanosecond
precision.</p></td>
            </tr>
          <tr valign='top' id='BOOLEAN_PROPERTY_PROC'>
            <td class="attr-name">BOOLEAN_PROPERTY_PROC</td>
            <td>=</td>
            <td class="attr-value"><pre>-&gt; ( value ) {
value.to_s.downcase == &#39;yes&#39; || value == true ? true : false
}</pre></td>
          </tr>
            <tr valign='top'>
              <td>&nbsp;</td>
              <td colspan="2" class="attr-desc"><p>Used by <a href="Headers.html#HEADER_TO_PROPERTY">HEADER_TO_PROPERTY</a>;
this Proc when called with some non-nil value from an HTTP header
representing a Boolean as “yes” or “no”, evaluates to either
<code>true</code> for “yes” or <code>false</code> for any other value. Case
insensitive.</p></td>
            </tr>
          <tr valign='top' id='BOOLEAN_HEADER_PROC'>
            <td class="attr-name">BOOLEAN_HEADER_PROC</td>
            <td>=</td>
            <td class="attr-value"><pre>-&gt; ( value ) { value == true ? &#39;yes&#39; : &#39;no&#39; }</pre></td>
          </tr>
            <tr valign='top'>
              <td>&nbsp;</td>
              <td colspan="2" class="attr-desc"><p>Used by <a href="Headers.html#HEADER_TO_PROPERTY">HEADER_TO_PROPERTY</a>;
this Proc when called with <code>true</code> or <code>false</code>
evaluates to String “yes” for <code>true</code> or “no” for any other
value.</p></td>
            </tr>
          <tr valign='top' id='HEADER_TO_PROPERTY'>
            <td class="attr-name">HEADER_TO_PROPERTY</td>
            <td>=</td>
            <td class="attr-value"><pre>{
# Take care not to define any property name which clashes with an
# option in any other part of this entire system where these &quot;other
# options&quot; get merged in. A project search for
# &#39;HEADER_TO_PROPERTY&#39; in comments should find those.

&#39;HTTP_X_RESOURCE_UUID&#39; =&gt; {
:property      =&gt; :resource_uuid,
:property_proc =&gt; UUID_PROPERTY_PROC,
:header        =&gt; &#39;X-Resource-UUID&#39;,
:header_proc   =&gt; UUID_HEADER_PROC,

:secured       =&gt; true,
},

&#39;HTTP_X_ASSUME_IDENTITY_OF&#39; =&gt; {
:property      =&gt; :assume_identity_of,
:property_proc =&gt; KVP_PROPERTY_PROC,
:header        =&gt; &#39;X-Assume-Identity-Of&#39;,
:header_proc   =&gt; KVP_HEADER_PROC,

:secured       =&gt; true,
:auto_transfer =&gt; true,
},

&#39;HTTP_X_DATED_AT&#39; =&gt; {
:property      =&gt; :dated_at,
:property_proc =&gt; DATETIME_IN_PAST_ONLY_PROPERTY_PROC,
:writer_proc   =&gt; DATETIME_WRITER_PROC,
:header        =&gt; &#39;X-Dated-At&#39;,
:header_proc   =&gt; DATETIME_HEADER_PROC,

:auto_transfer =&gt; true,
},

&#39;HTTP_X_DATED_FROM&#39; =&gt; {
:property      =&gt; :dated_from,
:property_proc =&gt; DATETIME_IN_PAST_ONLY_PROPERTY_PROC,
:writer_proc   =&gt; DATETIME_WRITER_PROC,
:header        =&gt; &#39;X-Dated-From&#39;,
:header_proc   =&gt; DATETIME_HEADER_PROC,

:auto_transfer =&gt; true,
},

&#39;HTTP_X_DEJA_VU&#39; =&gt; {
:property      =&gt; :deja_vu,
:property_proc =&gt; BOOLEAN_PROPERTY_PROC,
:header        =&gt; &#39;X-Deja-Vu&#39;,
:header_proc   =&gt; BOOLEAN_HEADER_PROC,
},
}</pre></td>
          </tr>
            <tr valign='top'>
              <td>&nbsp;</td>
              <td colspan="2" class="attr-desc"><p>Various “X-Foo”-style HTTP headers specified in the <a
href="../../Hoodoo.html">Hoodoo</a> API Specification have special meanings
and values for those need to be set up in request data and <a
href="../Client.html">Hoodoo::Client</a> endpoints. Processing around these
is data driven by this mapping Hash.</p>

<p>Keys are the HTTP header names in <a href="../../Rack.html">Rack</a> (upper
case, “HTTP_”-prefix) format. Values are options bundles as follows:</p>
<dl class="rdoc-list note-list"><dt><code>property</code>
<dd>
<p>The property name to be associated with the header, as a Symbol.</p>
</dd><dt><code>property_proc</code>
<dd>
<p>A Proc that&#39;s called to both validate and clean up the raw value from
the HTTP header. It evaluates to <code>nil</code> if the value is invalid,
or non-<code>nil</code> for any other case. Note that there is no way for
an HTTP header to explicitly convey a corresponding value internally of
<code>nil</code> as a result, by design; instead the relevant header would
simply be omitted by the caller (and/or change your header design!).</p>
</dd><dt><code>writer_proc</code>
<dd>
<p>If a property has a possible amigbuity of input data types when set
externally, independently of any validation etc. from the
<code>property_proc</code> option, then this optional entry contains a Proc
that is used for a custom write accessor and canonicalises assumed-valid
but possibly not canonical input for writing. An example would be the
conversion of String or Time instances to a DateTime so that a property
always reads back with a DateTime instance.</p>
</dd><dt><code>header</code>
<dd>
<p>For speed in lookups where it&#39;s needed, this is the “real” (not <a
href="../../Rack.html">Rack</a> format) HTTP header name.</p>
</dd><dt><code>header_proc</code>
<dd>
<p>A Proc that&#39;s called to convert a cleaned-up value set in the
<code>property</code> by its <code>property_proc</code>. It is called with
this value and returns an equivalent appropriate value for use with the
HTTP header given in <code>header</code>. This <em>MUST</em> always be a
String.</p>
</dd><dt><code>secured</code>
<dd>
<p>Optional, default <code>nil</code>. If <code>true</code>, marks that this
header and its associated value can only be processed if there is a Session
with a Caller that has an <code>authorised_http_headers</code> entry for
this header.</p>
</dd><dt><code>auto_transfer</code>
<dd>
<p>Optional, default <code>nil</code>. Only relevant to inter-resource call
scenarios. If <code>true</code>, when one resource calls another, the value
of this property is automatically transferred to the downstream resource.
Otherwise, it is not, and the downstream resource will operate under
whatever defaults are present. An inter-resource call endpoint which
inherits an auto-transfer property can always have this property explicitly
overwritten before any calls are made through it.</p>
</dd></dl>

<p>An additional key of <code>:property_writer</code> will be set up
automatically which contains the value of the <code>:property</code> key
with an “=” sign added, resulting in the name of a write accessor method
for that property.</p></td>
            </tr>
      </table>



    <!-- Methods -->
      <div class="sectiontitle">Class Public methods</div>
        <div class="method">
          <div class="title method-title" id="method-c-define_accessors_for_header_equivalents">
              <b>define_accessors_for_header_equivalents</b>( klass )
            <a href="../../../classes/Hoodoo/Client/Headers.html#method-c-define_accessors_for_header_equivalents" name="method-c-define_accessors_for_header_equivalents" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a series of read and custom write accessors according to the
HTTP_HEADER_OPTIONS_MAP. For example, a property of “dated_at” results in a
<code>dated_at</code> reader, a <code>dated_at=</code> writer which calls
<a
href="../Utilities.html#method-c-rationalise_datetime">Hoodoo::Utilities.rationalise_datetime</a>
to clean up the input value and sets the result into the
<code>@dated_at</code> instance variable which the read accessor will be
expecting to use.</p>
<dl class="rdoc-list note-list"><dt><code>klass</code>
<dd>
<p>The Class to which the instance methods will be added.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-define_accessors_for_header_equivalents_source')" id="l_method-c-define_accessors_for_header_equivalents_source">show</a>
              </p>
              <div id="method-c-define_accessors_for_header_equivalents_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/headers.rb, line 233</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">define_accessors_for_header_equivalents</span>( <span class="ruby-identifier">klass</span> )
  <span class="ruby-identifier">klass</span>.<span class="ruby-identifier">class_eval</span> <span class="ruby-keyword">do</span>
    <span class="ruby-constant">HEADER_TO_PROPERTY</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">rack_header</span>, <span class="ruby-identifier">description</span> <span class="ruby-operator">|</span>
      <span class="ruby-identifier">attr_reader</span>( <span class="ruby-identifier">description</span>[ <span class="ruby-value">:property</span> ] )

      <span class="ruby-identifier">custom_writer</span> = <span class="ruby-identifier">description</span>[ <span class="ruby-value">:writer_proc</span> ]

      <span class="ruby-keyword">if</span> <span class="ruby-identifier">custom_writer</span>.<span class="ruby-identifier">nil?</span>
        <span class="ruby-identifier">attr_writer</span>( <span class="ruby-identifier">description</span>[ <span class="ruby-value">:property</span> ] )
      <span class="ruby-keyword">else</span>
        <span class="ruby-identifier">define_method</span>( <span class="ruby-node">&quot;#{ description[ :property ] }=&quot;</span> ) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">parameter</span> <span class="ruby-operator">|</span>
          <span class="ruby-identifier">instance_variable_set</span>(
            <span class="ruby-node">&quot;@#{ description[ :property ] }&quot;</span>,
            <span class="ruby-identifier">description</span>[ <span class="ruby-value">:writer_proc</span> ].<span class="ruby-identifier">call</span>( <span class="ruby-identifier">parameter</span> )
          )
          <span class="ruby-identifier">result</span> = <span class="ruby-identifier">instance_variable_get</span>(<span class="ruby-node">&quot;@#{ description[ :property ] }&quot;</span>)
        <span class="ruby-keyword">end</span>
      <span class="ruby-keyword">end</span>
    <span class="ruby-keyword">end</span>
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-x_header_to_options">
              <b>x_header_to_options</b>( hashlike_source )
            <a href="../../../classes/Hoodoo/Client/Headers.html#method-c-x_header_to_options" name="method-c-x_header_to_options" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>From a Hash-like source where keys are HTTP header names and values are the
corresponding HTTP header values, extract interesting values and return a
Hash of options as described below.</p>

<p>Any <code>X-Foo</code> header is extracted, including core <a
href="../../Hoodoo.html">Hoodoo</a> extension headers such as
<code>X-Interaction-ID</code>, which is present in any response. The “X-”
is stripped, the rest converted to lower case and hyphens converted to
underscores. The interaction ID, therefore, would be set as an
<code>interaction_id</code> option. <code>X-Foo</code> would be set as a
<code>foo</code> option - and so-on.</p>

<p>The header matcher accepts headers from the Hash-like source in upper or
lower case with hyphens or underscores inside; extracted headers can
therefore start with any of <code>X_</code>, <code>x_</code>,
<code>X-</code> or <code>x-</code>. The Hash-like source must support the
<code>each</code> operator yielding a key and value to the block on each
iteration.</p>

<p>Header values are not translated at all, so (unless something very unsual
is going on) the option values will be Strings.</p>

<p>If the same header is encountered more than once, only the first one
encountered (in enumeration order, whatever that might be) is stored.</p>

<p>Parameters:</p>
<dl class="rdoc-list note-list"><dt><code>hashlike_source</code>
<dd>
<p>Hash-like source containing HTTP headers/values.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-x_header_to_options_source')" id="l_method-c-x_header_to_options_source">show</a>
              </p>
              <div id="method-c-x_header_to_options_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/headers.rb, line 282</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">x_header_to_options</span>( <span class="ruby-identifier">hashlike_source</span> )
  <span class="ruby-identifier">hashlike_source</span> <span class="ruby-operator">||=</span> {}
  <span class="ruby-identifier">options</span>           = {}

  <span class="ruby-identifier">hashlike_source</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">key</span>, <span class="ruby-identifier">value</span> <span class="ruby-operator">|</span>
    <span class="ruby-keyword">next</span> <span class="ruby-keyword">unless</span> ( <span class="ruby-identifier">key</span>[ <span class="ruby-number">0</span> ] <span class="ruby-operator">==</span> <span class="ruby-string">&#39;x&#39;</span> <span class="ruby-operator">||</span> <span class="ruby-identifier">key</span>[ <span class="ruby-number">0</span> ] <span class="ruby-operator">==</span> <span class="ruby-string">&#39;X&#39;</span> ) <span class="ruby-operator">&amp;&amp;</span>
                ( <span class="ruby-identifier">key</span>[ <span class="ruby-number">1</span> ] <span class="ruby-operator">==</span> <span class="ruby-string">&#39;-&#39;</span> <span class="ruby-operator">||</span> <span class="ruby-identifier">key</span>[ <span class="ruby-number">1</span> ] <span class="ruby-operator">==</span> <span class="ruby-string">&#39;_&#39;</span> )

    <span class="ruby-identifier">entry</span> = <span class="ruby-identifier">key</span>.<span class="ruby-identifier">to_s</span>.<span class="ruby-identifier">downcase</span>.<span class="ruby-identifier">gsub</span>( <span class="ruby-string">&#39;-&#39;</span>, <span class="ruby-string">&#39;_&#39;</span> )[ <span class="ruby-number">2</span><span class="ruby-operator">..</span><span class="ruby-number">-1</span> ]

    <span class="ruby-keyword">unless</span> <span class="ruby-identifier">entry</span> <span class="ruby-operator">==</span> <span class="ruby-string">&#39;&#39;</span> <span class="ruby-operator">||</span> <span class="ruby-identifier">options</span>.<span class="ruby-identifier">has_key?</span>( <span class="ruby-identifier">entry</span> )
      <span class="ruby-identifier">options</span>[ <span class="ruby-identifier">entry</span> ] = <span class="ruby-identifier">value</span>
    <span class="ruby-keyword">end</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">return</span> <span class="ruby-identifier">options</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
</div>

    </div>
  </body>
</html>
